Microsoft Cognitive Language Service - Question Answering (preview:2025-05-15)

2025/05/05 • 2 new methods

QuestionAnswering_GetAnswers (new)
Description :  Answers the specified question using your knowledge base.
Reference :  Link ¶

⚼ Request

POST:  /:query-knowledgebases
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
projectName:
{
Description: The name of the project to use. ,
Required: True ,
}
string ,
deploymentName:
{
Description: The name of the specific deployment of the project to use. ,
Required: True ,
}
string ,
knowledgeBaseQueryOptions:
{
Description: Post body of the request. ,
Required: True ,
}
{
qnaId:
{
Description: Exact QnA ID to fetch from the knowledge base, this field takes priority over question. ,
Format: int32 ,
Required: False ,
}
integer ,
question:
{
Description: User question to query against the knowledge base. ,
Required: False ,
}
string ,
top:
{
Description: Max number of answers to be returned for the question. ,
Format: int32 ,
Required: False ,
}
integer ,
userId:
{
Description: Unique identifier for the user. ,
Required: False ,
}
string ,
confidenceScoreThreshold:
{
Description: Minimum threshold score for answers, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
context:
{
Description: Context object with previous QnA's information. ,
Required: False ,
}
{
previousQnaId:
{
Description: Previous turn top answer result QnA ID. ,
Format: int32 ,
Required: True ,
}
integer ,
previousUserQuery:
{
Description: Previous user query. ,
Required: False ,
}
string ,
}
,
rankerType:
{
Description: Type of ranker to be used. ,
Enum:
{
QuestionOnly: Question only ranker. ,
Default: Default ranker. ,
}
,
Required: False ,
}
enum ,
filters:
{
Description: Filter QnAs based on given metadata list and knowledge base sources. ,
Required: False ,
}
{
metadataFilter:
{
Description: Find QnAs that are associated with the given list of metadata. ,
Required: False ,
}
{
metadata:
{
Description: Dictionary of string ,
Required: False ,
}
[
{
key:
{
Description: Metadata Key from Metadata dictionary used in the QnA. ,
Required: True ,
}
string ,
value:
{
Description: Metadata Value from Metadata dictionary used in the QnA. ,
Required: True ,
}
string ,
}
,
]
,
logicalOperation:
{
Description: Operation used to join metadata filters. ,
Enum:
{
AND: 'AND' for using corresponding logical operation. ,
OR: Set 'OR' for using corresponding logical operation. ,
}
,
Required: False ,
}
enum ,
}
,
sourceFilter:
{
Description: Find QnAs that are associated with any of the given list of sources in knowledge base. ,
Required: False ,
}
[
string ,
]
,
logicalOperation:
{
Description: Logical operation used to join metadata filter with source filter. ,
Enum:
{
AND: 'AND' for using corresponding logical operation. ,
OR: Set 'OR' for using corresponding logical operation. ,
}
,
Required: False ,
}
enum ,
}
,
answerSpanRequest:
{
Description: To configure Answer span prediction feature. ,
Required: False ,
}
{
enable:
{
Description: Enable or disable Answer Span prediction. ,
Required: True ,
}
boolean ,
confidenceScoreThreshold:
{
Description: Minimum threshold score required to include an answer span, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
topAnswersWithSpan:
{
Description: Number of Top answers to be considered for span prediction from 1 to 10. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
includeUnstructuredSources:
{
Description: (Optional) Flag to enable Query over Unstructured Sources. ,
Required: False ,
}
boolean ,
queryPreferences:
{
Description: To fine tune query results ,
Required: False ,
}
{
scorer:
{
Description: To specify what scoring algorithm is preferred ,
Enum:
{
Classic: Set this value for scoring based on classic algorithms like wordnet, tfidf, ngram etc. ,
Transformer: Set this value for scoring based on transformer based models. ,
Semantic: Set this scorer to use AI search semantic based ranking. Semantic ranking should be configured for this to be used. ,
}
,
Required: False ,
}
enum ,
matchingPolicy:
{
Description: Policy for controling exact query match behavior ,
Required: False ,
}
{
kind:
{
Description: Kind of matching policy to be applied ,
Enum:
{
Prebuilt: Prebuilt weights will be used for giving preference to question and answer columns when quering AI search ,
}
,
Required: True ,
}
enum ,
}
,
}
,
}
,
}

⚐ Response (200)

{
answers:
{
Description: Represents Answer Result list. ,
Required: False ,
}
[
{
questions:
{
Description: List of questions associated with the answer. ,
Required: False ,
}
[
string ,
]
,
answer:
{
Description: Answer text. ,
Required: False ,
}
string ,
confidenceScore:
{
Description: Answer confidence score, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
id:
{
Description: ID of the QnA result. ,
Format: int32 ,
Required: False ,
}
integer ,
source:
{
Description: Source of QnA result. ,
Required: False ,
}
string ,
metadata:
{
Description: Metadata associated with the answer, useful to categorize or filter question answers. ,
Required: False ,
}
object ,
dialog:
{
Description: Dialog associated with Answer. ,
Required: False ,
}
{
isContextOnly:
{
Description: To mark if a prompt is relevant only with a previous question or not. If true, do not include this QnA as search result for queries without context; otherwise, if false, ignores context and includes this QnA in search result. ,
Required: False ,
}
boolean ,
prompts:
{
Description: List of prompts associated with the answer. ,
Required: False ,
}
[
{
displayOrder:
{
Description: Index of the prompt - used in ordering of the prompts. ,
Format: int32 ,
Required: False ,
}
integer ,
qnaId:
{
Description: QnA ID corresponding to the prompt. ,
Format: int32 ,
Required: False ,
}
integer ,
displayText:
{
Description: Text displayed to represent a follow up question prompt. ,
Required: False ,
}
string ,
}
,
]
,
}
,
answerSpan:
{
Description: Answer span object of QnA with respect to user's question. ,
Required: False ,
}
{
text:
{
Description: Predicted text of answer span. ,
Required: False ,
}
string ,
confidenceScore:
{
Description: Predicted score of answer span, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
offset:
{
Description: The answer span offset from the start of answer. ,
Format: int32 ,
Required: False ,
}
integer ,
length:
{
Description: The length of the answer span. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
}
,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: String error code indicating what went wrong. ,
}
string ,
}
,
$schema:
{
Description: Error response. ,
}
{
error:
{
Description: The error object. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Enum:
{
InvalidRequest: Invalid request error ,
InvalidArgument: Invalid argument error ,
Unauthorized: Unauthorized access error ,
Forbidden: Forbidden access error ,
NotFound: Not found error ,
ProjectNotFound: Project not found error ,
OperationNotFound: Operation not found error ,
AzureCognitiveSearchNotFound: Azure Cognitive Search not found error ,
AzureCognitiveSearchIndexNotFound: Azure Cognitive Search index not found error ,
TooManyRequests: Too many requests error ,
AzureCognitiveSearchThrottling: Azure Cognitive Search throttling error ,
AzureCognitiveSearchIndexLimitReached: Azure Cognitive Search index limit reached error ,
InternalServerError: Internal server error ,
ServiceUnavailable: Service unavailable error ,
Timeout: Timeout error ,
QuotaExceeded: Quota exceeded error ,
Conflict: Conflict error ,
Warning: Warning error ,
}
,
Required: True ,
}
enum ,
message:
{
Description: A human-readable representation of the error. ,
Required: True ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Enum:
{
InvalidRequest: Invalid request error ,
InvalidParameterValue: Invalid parameter value error ,
KnowledgeBaseNotFound: Knowledge base not found error ,
AzureCognitiveSearchNotFound: Azure Cognitive Search not found error ,
AzureCognitiveSearchThrottling: Azure Cognitive Search throttling error ,
ExtractionFailure: Extraction failure error ,
InvalidRequestBodyFormat: Invalid request body format error ,
EmptyRequest: Empty request error ,
MissingInputDocuments: Missing input documents error ,
InvalidDocument: Invalid document error ,
ModelVersionIncorrect: Model version incorrect error ,
InvalidDocumentBatch: Invalid document batch error ,
UnsupportedLanguageCode: Unsupported language code error ,
InvalidCountryHint: Invalid country hint error ,
}
,
Required: True ,
}
enum ,
message:
{
Description: Error message. ,
Required: True ,
}
string ,
details:
{
Description: Error details. ,
Required: False ,
}
object ,
target:
{
Description: Error target. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}
QuestionAnswering_GetAnswersFromText (new)
Description :  Answers the specified question using the provided text in the body.
Reference :  Link ¶

⚼ Request

POST:  /:query-text
{
api-version:
{
Description: The API version to use for this operation. ,
Required: True ,
}
string ,
textQueryOptions:
{
Description: Post body of the request. ,
Required: True ,
}
{
question:
{
Description: User question to query against the given text records. ,
Required: True ,
}
string ,
records:
{
Description: Text records to be searched for given question. ,
Required: True ,
}
[
{
id:
{
Description: Unique identifier for the text record. ,
Required: True ,
}
string ,
text:
{
Description: Text contents of the record. ,
Required: True ,
}
string ,
}
,
]
,
language:
{
Description: Language of the text records. This is BCP-47 representation of a language. For example, use "en" for English; "es" for Spanish etc. If not set, use "en" for English as default. ,
Required: False ,
}
string ,
stringIndexType:
{
Description: Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets. ,
Enum:
{
TextElements_v8: Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo. ,
UnicodeCodePoint: Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python. ,
Utf16CodeUnit: Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript. ,
}
,
Required: False ,
}
enum ,
}
,
}

⚐ Response (200)

{
answers:
{
Description: Represents the answer results. ,
Required: False ,
}
[
{
answer:
{
Description: Answer. ,
Required: False ,
}
string ,
confidenceScore:
{
Description: answer confidence score, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
id:
{
Description: record ID. ,
Required: False ,
}
string ,
answerSpan:
{
Description: Answer span object with respect to user's question. ,
Required: False ,
}
{
text:
{
Description: Predicted text of answer span. ,
Required: False ,
}
string ,
confidenceScore:
{
Description: Predicted score of answer span, value ranges from 0 to 1. ,
Format: double ,
Required: False ,
}
number ,
offset:
{
Description: The answer span offset from the start of answer. ,
Format: int32 ,
Required: False ,
}
integer ,
length:
{
Description: The length of the answer span. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
offset:
{
Description: The sentence offset from the start of the document. ,
Format: int32 ,
Required: False ,
}
integer ,
length:
{
Description: The length of the sentence. ,
Format: int32 ,
Required: False ,
}
integer ,
}
,
]
,
}

⚐ Response (default)

{
$headers:
{
x-ms-error-code:
{
Description: String error code indicating what went wrong. ,
}
string ,
}
,
$schema:
{
Description: Error response. ,
}
{
error:
{
Description: The error object. ,
Required: True ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Enum:
{
InvalidRequest: Invalid request error ,
InvalidArgument: Invalid argument error ,
Unauthorized: Unauthorized access error ,
Forbidden: Forbidden access error ,
NotFound: Not found error ,
ProjectNotFound: Project not found error ,
OperationNotFound: Operation not found error ,
AzureCognitiveSearchNotFound: Azure Cognitive Search not found error ,
AzureCognitiveSearchIndexNotFound: Azure Cognitive Search index not found error ,
TooManyRequests: Too many requests error ,
AzureCognitiveSearchThrottling: Azure Cognitive Search throttling error ,
AzureCognitiveSearchIndexLimitReached: Azure Cognitive Search index limit reached error ,
InternalServerError: Internal server error ,
ServiceUnavailable: Service unavailable error ,
Timeout: Timeout error ,
QuotaExceeded: Quota exceeded error ,
Conflict: Conflict error ,
Warning: Warning error ,
}
,
Required: True ,
}
enum ,
message:
{
Description: A human-readable representation of the error. ,
Required: True ,
}
string ,
target:
{
Description: The target of the error. ,
Required: False ,
}
string ,
details:
{
Description: An array of details about specific errors that led to this reported error. ,
Required: False ,
}
[
string ,
]
,
innererror:
{
Description: An object containing more specific information than the current object about the error. ,
Required: False ,
}
{
code:
{
Description: One of a server-defined set of error codes. ,
Enum:
{
InvalidRequest: Invalid request error ,
InvalidParameterValue: Invalid parameter value error ,
KnowledgeBaseNotFound: Knowledge base not found error ,
AzureCognitiveSearchNotFound: Azure Cognitive Search not found error ,
AzureCognitiveSearchThrottling: Azure Cognitive Search throttling error ,
ExtractionFailure: Extraction failure error ,
InvalidRequestBodyFormat: Invalid request body format error ,
EmptyRequest: Empty request error ,
MissingInputDocuments: Missing input documents error ,
InvalidDocument: Invalid document error ,
ModelVersionIncorrect: Model version incorrect error ,
InvalidDocumentBatch: Invalid document batch error ,
UnsupportedLanguageCode: Unsupported language code error ,
InvalidCountryHint: Invalid country hint error ,
}
,
Required: True ,
}
enum ,
message:
{
Description: Error message. ,
Required: True ,
}
string ,
details:
{
Description: Error details. ,
Required: False ,
}
object ,
target:
{
Description: Error target. ,
Required: False ,
}
string ,
innererror:
{
Required: False ,
}
string ,
}
,
}
,
}
,
}